Nested Documentation
Nested documentation refers to documentation objects that are ultimately parsed and added to some parent documentation object.
The original AngularJS implementation allows for methods and properties to be defined next to the code that defined the actual properties and methods. This is ideal and provides better documentation, but as you might guess, creates a situation where separate documentation objects need to be merged as one.
To solve this problem, there are documentation fields that allow a documentation object to be associated as a child of another documentation object. After all documentation objects are created, a separate process scans each documentation object and then merges it with the appropriate parent object when it is identified as a "nested" or child documentation object.
The best way to explain this is by showing an example. Suppose we have an interface:
/** * @doc interface * @name example.class:example_interface * @description This is my example interface description * @property {string} name * @property {number} age * @method {function} booyah */ var example_interface = { name : '', age : 5, booyah: function () { alert('booyah'); } };
That's great and works fine, but there are two things wrong.
First, you have to define your methods and properties within the original parent comment block. This keeps the documentation away from where the actual properties and methods are defined in the code. Although here the visual disconnect is small, but imagine a more robust and larger class/interface.
Second, methods have a lot more going on that requires more fields to help elaborate on the use of a method. This is just not possible without creating some crazy namespace issues within the parent documentation object.
Therefore, you can create new documentation objects and refer to the parentID, so they will be absorbed as children and parsed and rendered as expected.
/** * @doc interface * @name example.class:example_interface * @description This is my example interface description * @property {string} name * @property {number} age * @method {function} booyah */ var example_interface = { /** * @doc property * @propertyOf example.class:example_interface * @name example.class:example_interface#name * @description This is the name property */ name : '', /** * @doc property * @propertyOf example.class:example_interface * @name example.class:example_interface#age * @description This is the age property */ age : 5, /** * @doc method * @methodOf example.class:example_interface * @name example.class:example_interface#booyah * @description This is the booyah method */ booyah: function () { alert('booyah'); } };
Currently, method
and property
are the only 'nested' documentation objects that will merge with the parents, howerver this is certainly extendable in the future.
Here is a better working example. The interface example will show how it renders. You can then click the "show source" button on the page to view the original documentation objects. Notice how there are multiple documentation objects highlighted.